<HTML>
<HEAD>
<TITLE>[Chapter 10] Would You Like to Choose from the Menu?</TITLE>
<META NAME="author" CONTENT="John Zukowski">
<META NAME="date" CONTENT="Thu Jul 31 14:46:09 1997">
<META NAME="form" CONTENT="html">
<META NAME="metadata" CONTENT="dublincore.0.1">
<META NAME="objecttype" CONTENT="book part">
<META NAME="otheragent" CONTENT="gmat dbtohtml">
<META NAME="publisher" CONTENT="O'Reilly &amp; Associates, Inc.">
<META NAME="source" CONTENT="SGML">
<META NAME="subject" CONTENT="Java AWT">
<META NAME="title" CONTENT="Java AWT">
<META HTTP-EQUIV="Content-Script-Type" CONTENT="text/javascript">
</HEAD>
<body vlink="#551a8b" alink="#ff0000" text="#000000" bgcolor="#FFFFFF" link="#0000ee">

<DIV CLASS=htmlnav>
<H1><a href='index.htm'><IMG SRC="gifs/smbanner.gif"
     ALT="Java AWT" border=0></a></H1>
<table width=515 border=0 cellpadding=0 cellspacing=0>
<tr>
<td width=172 align=left valign=top><A HREF="ch09_05.htm"><IMG SRC="gifs/txtpreva.gif" ALT="Previous" border=0></A></td>
<td width=171 align=center valign=top><B><FONT FACE="ARIEL,HELVETICA,HELV,SANSERIF" SIZE="-1">Chapter 10</FONT></B></TD>
<td width=172 align=right valign=top><A HREF="ch10_02.htm"><IMG SRC="gifs/txtnexta.gif" ALT="Next" border=0></A></td>
</tr>
</table>

&nbsp;
<hr align=left width=515>
</DIV>
<H1 CLASS=chapter><A CLASS="TITLE" NAME="JAWT-CH-10">10. Would You Like to Choose from the Menu?</A></H1>

<DIV CLASS=htmltoc>

<p>
<b>Contents:</b><br>
MenuComponent<br>
<A HREF="ch10_02.htm">MenuContainer</A><BR>
<A HREF="ch10_03.htm">MenuShortcut</A><BR>
<A HREF="ch10_04.htm">MenuItem</A><BR>
<A HREF="ch10_05.htm">Menu</A><BR>
<A HREF="ch10_06.htm">CheckboxMenuItem</A><BR>
<A HREF="ch10_07.htm">MenuBar</A><BR>
<A HREF="ch10_08.htm">Putting It All Together</A><BR>
<A HREF="ch10_09.htm">PopupMenu</A><BR>

<p>
</DIV>

<P CLASS=para>
In <A HREF="ch06_01.htm">Chapter 6, <i>Containers</i></A>, 
I mentioned that a <tt CLASS=literal>Frame</tt> can 
have a menu. Indeed, to offer a menu in the AWT, you have to attach it 
to a <tt CLASS=literal>Frame</tt>. With versions 1.0.2 
and 1.1, Java does not support menu bars within an applet or any other 
container. We hope that future versions of Java will allow menus to be 
used with other containers. Java 1.1 goes partway toward solving this 
problem by introducing a <tt CLASS=literal>PopupMenu</tt> 
that lets you attach context menus to any <tt CLASS=literal>Component</tt>. 
Java 1.1 also adds <tt CLASS=literal>MenuShortcut</tt> 
events, which represent keyboard accelerator events for menus. <A NAME="CH10.MENU1"></A>

<P CLASS=para>
Implementing a menu in a <tt CLASS=literal>Frame</tt> 
involves connections among a number of different objects: <tt CLASS=literal>MenuBar</tt>, 
<tt CLASS=literal>Menu</tt>, <tt CLASS=literal>MenuItem</tt>, 
and the optional <tt CLASS=literal>CheckboxMenuItem</tt>. 
Several of these classes implement the <tt CLASS=literal>MenuContainer</tt> 
interface. Once you've created a few menus, you'll probably 
find the process quite natural, but it's hard to describe until you 
see what all the objects are. So this chapter describes most of the menu 
classes first and then shows an example demonstrating their use. 

<P CLASS=para>
All the components covered in previous chapters were subclasses of <tt CLASS=literal>Component</tt>. 
Most of the objects in this chapter subclass <tt CLASS=literal>MenuComponent</tt>, 
which encapsulates the common functionality of menu objects. The <tt CLASS=literal>MenuComponent</tt> 
class hierarchy is shown in <A HREF="ch10_01.htm#JAWT-CH-10-FIG-1">Figure 10.1</A>. 

<DIV CLASS=figure>
<h4 CLASS=figure><A CLASS="TITLE" NAME="JAWT-CH-10-FIG-1">Figure 10.1: MenuComponent class hierarchy</A></h4>


<p>
<img align=middle src="./figs/jawt1001.gif" alt="[Graphic: Figure 10-1]" width=466 height=652 border=0>

</DIV>

<P CLASS=para>
To display a <tt CLASS=literal>Menu</tt>, you must first put it in a <tt CLASS=literal>MenuBar</tt>, which you add to a <tt CLASS=literal>Frame</tt>. (Pop-up menus are different in that they don't need a <tt CLASS=literal>Frame</tt>.) A <tt CLASS=literal>Menu</tt> can contain <tt CLASS=literal>MenuItem</tt> 
as well as other menus that 
form submenus. <tt CLASS=literal>CheckboxMenuItem</tt> 
is a specialized <tt CLASS=literal>MenuItem</tt> that 
(as you might guess) the user can toggle like a <tt CLASS=literal>Checkbox</tt>. 
One way to visualize how all these things work together is to imagine a 
set of curtains. The different <tt CLASS=literal>MenuItem</tt> 
components are the fabrics and panels that make up the curtains. The <tt CLASS=literal>Menus</tt> 
are the curtains. They get hung from the <tt CLASS=literal>MenuBar</tt>, 
which is like a curtain rod. Then you place the <tt CLASS=literal>MenuBar</tt> 
curtain rod into the <tt CLASS=literal>Frame</tt> 
(the window, in our metaphor), curtains and all. 

<P CLASS=para>
It might puzzle you that a <tt CLASS=literal>Menu</tt> is a subclass of 
<tt CLASS=literal>MenuItem</tt>, not the other way 
around. This is because a <tt CLASS=literal>Menu</tt> 
can appear on a <tt CLASS=literal>Menu</tt> just like 
another <tt CLASS=literal>MenuItem</tt>, which would 
not be possible if the hierarchy was the other way around. <A HREF="ch10_01.htm#JAWT-CH-10-FIG-2">Figure 10.2</A> 
points out the different pieces involved in the creation of a menu: the <tt CLASS=literal>MenuBar</tt> and various kinds of menu items, including a submenu.

<DIV CLASS=figure>
<h4 CLASS=figure><A CLASS="TITLE" NAME="JAWT-CH-10-FIG-2">Figure 10.2: The pieces that make up a Menu</A></h4>


<p>
<img align=middle src="./figs/jawt1002.gif" alt="[Graphic: Figure 10-2]" width=185 height=185 border=0>

</DIV>

<DIV CLASS=sect1>
<h2 CLASS=sect1><A CLASS="TITLE" NAME="JAWT-CH-10-SECT-1">10.1 MenuComponent</A></h2>

<P CLASS=para>
<A NAME="CH10.MENU7"></A><tt CLASS=literal>MenuComponent</tt> is an abstract 
class that is the parent of all menu-related objects. You will never create 
an instance of the object. Nor are you likely to subclass it yourself--to 
make the subclass work, you'd have to provide your own peer on every 
platform where you want the application to run. 

<DIV CLASS=sect2>
<h3 CLASS=sect2><A CLASS="TITLE" NAME="JAWT-CH-10-SECT-1.1">MenuComponent Methods</A></h3>Constructor

<P>
<DL CLASS=variablelist>
<DT CLASS=varlistentry><I CLASS=emphasis>public MenuComponent ()--cannot be called directly </I><br>
<DD>

<P CLASS=para>
Since <tt CLASS=literal>MenuComponent</tt> is an abstract 
class, you cannot create an instance of the object. This method is called 
when you create an instance of one of its children. </DL>
Fonts

<P>
<DL CLASS=variablelist>
<DT CLASS=varlistentry><I CLASS=emphasis>public Font getFont () </I><br>
<DD>

<P CLASS=para>
The <tt CLASS=literal>getFont()</tt> method retrieves 
the font associated with the <tt CLASS=literal>MenuComponent</tt> 
from <tt CLASS=literal>setFont()</tt>. If the current 
object's font has not been set, the parent menu's font is retrieved. 
If there is no parent and the current object's font has not been 
set, <tt CLASS=literal>getFont()</tt> returns <tt CLASS=literal>null</tt>. 

<p>
<DT CLASS=varlistentry><I CLASS=emphasis>public void setFont (Font f) </I><br>
<DD>

<P CLASS=para>
The <tt CLASS=literal>setFont()</tt> method allows 
you to change the font of the particular menu-related component to <tt CLASS=literal>f</tt>. 
When a <tt CLASS=literal>MenuComponent</tt> is first 
created, the initial font is <tt CLASS=literal>null</tt>, 
so the parent menu's font is used. </DL>
<DIV CLASS=note>
<P CLASS=note><BLOCKQUOTE><P><B>NOTE:</B> 
</blockquote><P>
</DIV>

<P CLASS=para>
Some platforms do not support changing the fonts of menu items. Where 
supported, it can make some pretty ugly menus. 
</blockquote><P>
</DIV>

Names

<P CLASS=para>
The name serves as an alternative, nonlocalized reference identifier for 
menu components. If your event handlers compare menu label strings to an 
expected value and labels are localized for a new environment, the approach 
fails. 

<P>
<DL CLASS=variablelist>
<DT CLASS=varlistentry><I CLASS=emphasis>public String getName () </I><br>
<DD>

<P CLASS=para>
The <tt CLASS=literal>getName()</tt> method retrieves 
the name of the menu component. Every instance of a subclass of <tt CLASS=literal>MenuComponent</tt> 
is named when it is created. 

<p>
<DT CLASS=varlistentry><I CLASS=emphasis>public void setName (String name) </I><br>
<DD>

<P CLASS=para>
The <tt CLASS=literal>setName()</tt> method changes 
the current name of the component to <tt CLASS=literal>name</tt>. </DL>
Peers

<P>
<DL CLASS=variablelist>
<DT CLASS=varlistentry><I CLASS=emphasis>public MenuComponentPeer getPeer () <img src="gifs/wstar.gif" alt="(Deprecated)" border=0> </I><br>
<DD>

<P CLASS=para>
The <tt CLASS=literal>getPeer()</tt> method returns 
a reference to the <tt CLASS=literal>MenuComponent</tt> 
peer as a <tt CLASS=literal>MenuComponentPeer</tt>. 

<p>
<DT CLASS=varlistentry><I CLASS=emphasis>public synchronized void removeNotify ()  </I><br>
<DD>

<P CLASS=para>
The <tt CLASS=literal>removeNotify()</tt> method destroys 
the peer of the <tt CLASS=literal>MenuComponent</tt> 
and removes it from the screen. <tt CLASS=literal>addNotify()</tt> 
will be specific to the subclass. </DL>
Events

<P CLASS=para>
Event handling is slightly different between versions. If using the 1.0 
event model, use <tt CLASS=literal>postEvent()</tt>. 
Otherwise, use <tt CLASS=literal>dispatchEvent()</tt> to post an event to this <tt CLASS=literal>MenuComponent</tt> or <tt CLASS=literal>processEvent()</tt> to receive and handle an event. Remember not to mix versions within your programs. 

<P>
<DL CLASS=variablelist>
<DT CLASS=varlistentry><I CLASS=emphasis>public boolean postEvent (Event e) <img src="gifs/wstar.gif" alt="(Deprecated)" border=0>  </I><br>
<DD>

<P CLASS=para>
The <tt CLASS=literal>postEvent()</tt> method posts 
<tt CLASS=literal>Event</tt> <tt CLASS=literal>e</tt> 
to the <tt CLASS=literal>MenuComponent</tt>. The event 
is delivered to the <tt CLASS=literal>Frame</tt> at 
the top of the object hierarchy that contains the selected <tt CLASS=literal>MenuComponent</tt>. 
The only way to capture this event before it gets handed to the <tt CLASS=literal>Frame</tt> 
is to override this method. There are no helper functions as there are 
for <tt CLASS=literal>Components</tt>. Find out which 
<tt CLASS=literal>MenuComponent</tt> triggered the 
event by checking <tt CLASS=literal>e.arg</tt>, which 
contains its label, or <tt CLASS=literal>((MenuItem)e.target).getName()</tt> 
for the nonlocalized name of the target. 

<DIV CLASS=screen>
<P>
<PRE>
public boolean postEvent (Event e) {
    // Use getName() vs. e.arg for localization possibility
    if ("About".equals (((MenuItem)e.target).getName()))
        playLaughingSound(); // Help request
    return super.postEvent (e);
}
</PRE>
</DIV>

<P CLASS=para>
If you override this method, in order for this <tt CLASS=literal>Event</tt> 
to propagate to the <tt CLASS=literal>Frame</tt> that 
contains the <tt CLASS=literal>MenuComponent</tt>, 
you must call the original <tt CLASS=literal>postEvent()</tt> 
method (<tt CLASS=literal>super.postEvent(e)</tt>). 

<P CLASS=para>
The actual value returned by <tt CLASS=literal>postEvent()</tt> 
is irrelevant. 

<p>
<DT CLASS=varlistentry><I CLASS=emphasis>public final void dispatchEvent(AWTEvent e) <img src="gifs/bstar.gif" alt="(New)" border=0></I><br>
<DD>

<P CLASS=para>
The <tt CLASS=literal>dispatchEvent()</tt> method allows you to post new AWT events to this menu component's listeners. <tt CLASS=literal>dispatchEvent()</tt> tells the <tt CLASS=literal>MenuComponent</tt> to deal with the <tt CLASS=literal>AWTEvent e</tt> by calling its <tt CLASS=literal>processEvent()</tt> method. This method is similar to Java 1.0's <tt CLASS=literal>postEvent()</tt> method. Events delivered in this way bypass the system's event queue. It's not clear why you would want to bypass the event queue, except possibly to deliver some kind of high priority event.

<p>
<DT CLASS=varlistentry><I CLASS=emphasis>protected void processEvent(AWTEvent e) <img src="gifs/bstar.gif" alt="(New)" border=0> </I><br>
<DD>

<P CLASS=para>
The <tt CLASS=literal>processEvent()</tt> method receives 
all <tt CLASS=literal>AWTEvent</tt>s with a subclass 
of <tt CLASS=literal>MenuComponent</tt> as its target. 
<tt CLASS=literal>processEvent()</tt> then passes 
them along for processing. When you subclass a child class, overriding 
<tt CLASS=literal>processEvent()</tt> allows you to 
process all events without having to provide listeners. However, remember 
to call <tt CLASS=literal>super.processEvent(e)</tt> 
last to ensure regular functionality is still executed. This is like overriding 
<tt CLASS=literal>postEvent()</tt> using the 1.0 event 
model. </DL>
Miscellaneous methods

<P>
<DL CLASS=variablelist>
<DT CLASS=varlistentry><I CLASS=emphasis>public MenuContainer getParent () </I><br>
<DD>

<P CLASS=para>
The <tt CLASS=literal>getParent()</tt> method returns 
the parent <tt CLASS=literal>MenuContainer</tt> for 
the <tt CLASS=literal>MenuComponent</tt>. <tt CLASS=literal>MenuContainer</tt> 
is an interface that is implemented by <tt CLASS=literal>Component</tt> 
(in 1.1 only), <tt CLASS=literal>Frame</tt>, <tt CLASS=literal>Menu</tt>, 
and <tt CLASS=literal>MenuBar</tt>. This means that 
<tt CLASS=literal>getParent()</tt> could return any 
one of the four. 

<p>
<DT CLASS=varlistentry><I CLASS=emphasis>protected String paramString ()</I><br>
<DD>

<P CLASS=para>
The <tt CLASS=literal>paramString()</tt> method of 
<tt CLASS=literal>MenuComponent</tt> helps build up 
the string to display when <tt CLASS=literal>toString()</tt> 
is called for a subclass. At the <tt CLASS=literal>MenuComponent</tt> 
level, the current name of the object is appended to the output. 

<p>
<DT CLASS=varlistentry><I CLASS=emphasis>public String toString ()--can be called by user for subclass </I><br>
<DD>

<P CLASS=para>
The <tt CLASS=literal>toString()</tt> method at the 
<tt CLASS=literal>MenuComponent</tt> level cannot 
be called directly. This <tt CLASS=literal>toString()</tt> 
method is called when you call a subclass's <tt CLASS=literal>toString()</tt> 
and the specifics of the subclass is added between the brackets ([ and ]). 
At this level, the results would be: 

<DIV CLASS=screen>
<P>
<PRE>
java.awt.MenuComponent[aname1]
</PRE>
</DIV>

</DL>
</DIV>

</DIV>


<DIV CLASS=htmlnav>

<P>
<HR align=left width=515>
<table width=515 border=0 cellpadding=0 cellspacing=0>
<tr>
<td width=172 align=left valign=top><A HREF="ch09_05.htm"><IMG SRC="gifs/txtpreva.gif" ALT="Previous" border=0></A></td>
<td width=171 align=center valign=top><a href="index.htm"><img src='gifs/txthome.gif' border=0 alt='Home'></a></td>
<td width=172 align=right valign=top><A HREF="ch10_02.htm"><IMG SRC="gifs/txtnexta.gif" ALT="Next" border=0></A></td>
</tr>
<tr>
<td width=172 align=left valign=top>ItemSelectable</td>
<td width=171 align=center valign=top><a href="index/idx_a.htm"><img src='gifs/index.gif' alt='Book Index' border=0></a></td>
<td width=172 align=right valign=top>MenuContainer</td>
</tr>
</table>
<hr align=left width=515>

<IMG SRC="gifs/smnavbar.gif" USEMAP="#map" BORDER=0> 
<MAP NAME="map"> 
<AREA SHAPE=RECT COORDS="0,0,108,15" HREF="../javanut/index.htm"
alt="Java in a Nutshell"> 
<AREA SHAPE=RECT COORDS="109,0,200,15" HREF="../langref/index.htm" 
alt="Java Language Reference"> 
<AREA SHAPE=RECT COORDS="203,0,290,15" HREF="../awt/index.htm" 
alt="Java AWT"> 
<AREA SHAPE=RECT COORDS="291,0,419,15" HREF="../fclass/index.htm" 
alt="Java Fundamental Classes"> 
<AREA SHAPE=RECT COORDS="421,0,514,15" HREF="../exp/index.htm" 
alt="Exploring Java"> 
</MAP>
</DIV>

</BODY>
</HTML>
